
package org.xml.sax;

/**
 * 接收基本DTD相关事件的通知的接口。
 *
 *如果一个SAX应用程序需要关于符号和未解析实体的信息，
 * 那么应用程序将使用解析器的DTDHandler方法实现此接口并向SAX解析器注册一个实例。
 *
 * 解析器使用该实例向应用程序报告记法和未解析的实体声明。
 *
 * 请注意，此接口仅包含XML建议要求处理器报告的那些DTD事件：符号和未分析的实体声明。
 * SAX解析器可以以任何顺序报告这些事件，而不管符号和未分析实体的声明顺序如何;
 * 但是，所有DTD事件都必须在文档处理程序的开始文档事件之后和第一个开始元素事件之前报告。
 * （如果使用{@link org.xml.sax.ext.LexicalHandler LexicalHandler} ，则这些事件也必须在结束DTD事件之前被报告。）
 *
 * 这是由应用程序来存储信息以供将来使用（也许在散列表或对象树中）.
 * 如果应用程序遇到“NOTATION”，“ENTITY”或“ENTITIES”类型的属性，
 * 它可以使用它通过此接口获得的信息来查找与属性值相对应的实体和/或符号。</p>
 *
 * @since SAX 1.0
 * @author David Megginson
 * @version 2.0.1 (sax2r2)
 * @see org.xml.sax.XMLReader#setDTDHandler
 */
public interface DTDHandler {


    /**
     * 接收符号（注释）声明事件的通知。
     *
     *
     *
     * 记录符号以供日后参考，如果有必要的话;符号可能以属性值的形式出现在未解析的实体声明中，
     * 有时用于处理指令目标名称。
     *
     * 公共ID和系统ID中的至少一个必须是非空的。
     * 如果系统标识符存在，并且是一个URL，SAX解析器必须在通过此事件将其传递给应用程序之前将其完全解析。
     *
     * 无法保证在使用它的任何未经分析的实体之前，将会报告符号声明。
     *
     * @param name 符号名称。
     * @param publicId 符号的公共标识符，如果没有提供，则返回null。
     * @param systemId 符号的系统标识符，如果没有提供，则返回null。
     * @exception org.xml.sax.SAXException Any SAX exception, possibly wrapping another exception.
     * @see #unparsedEntityDecl
     * @see org.xml.sax.Attributes
     */
    public abstract void notationDecl (String name,
                       String publicId,
                       String systemId)
    throws SAXException;


    /**
     * 接收未解析实体声明事件的通知。
     *
     * 请注意，符号名称对应于由{@link #notationDecl notationDecl} 事件报告的符号。
     * 如有必要，由实体记录实体以供日后参考。 未分析的实体可能显示为属性值。
     *
     * <p>如果系统标识符是一个URL，则解析器必须在将其传递给应用程序之前将其完全解析。 </p>
     *
     * @exception org.xml.sax.SAXException Any SAX exception, possibly wrapping another exception.
     * @param name 未分析的实体的名称。
     * @param publicId 实体的公共标识符，如果没有提供，则返回null。
     * @param systemId 实体的系统标识符。
     * @param notationName 关联符号的名称。
     * @see #notationDecl
     * @see org.xml.sax.Attributes
     */
    public abstract void unparsedEntityDecl (String name,
                         String publicId,
                         String systemId,
                         String notationName)
    throws SAXException;

}

